---
title: 从 GitBook 迁移到 Astro
description: 将现有的 GitBook 项目迁移到 Astro 的提示
type: migration
stub: true
framework: GitBook
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

[GitBook](https://gitbook.com) 是一个基于网络的平台，可用于以协作方式创建和发布文档和书籍，具有版本控制集成和可定制特性。

## GitBook 和 Astro 的主要相似点

GitBook 与 Astro 之间有一些相似点，可以帮助你迁移项目：

- Astro 和 GitBook 都支持 [Markdown](/zh-cn/guides/markdown-content/)。你可以使用 GitBook 的 Git Sync 功能迁移所有现有的文档。

- Astro 和 GitBook 都使用某种形式的[基于文件的路由](/zh-cn/guides/routing/)。对于你现有的内容和添加新页面时使用 Astro 的文件结构应该感觉很熟悉。

## GitBook 和 Astro 的主要区别

当你将 GitBook 文档迁移到 Astro 时，你会注意到一些重要的区别：

- GitBook 网站是使用在线控制板进行编辑的。在 Astro 中，你将使用[代码编辑器](/zh-cn/editor-setup/)和开发环境来维护你的网站。你可以在本地进行开发，也可以选择像 StackBlitz、CodeSandbox 或 Gitpod 这样的云编辑器/开发环境。

- GitBook 将你的内容存储在数据库中。在 Astro 中，你的每个页面的内容都将有单独的文件（通常是 Markdown 或 MDX）位于你的[项目目录](/zh-cn/basics/project-structure/)中。或者，你可以选择使用[为你的内容提供 CMS](/zh-cn/guides/cms/)，并使用 Astro 来获取和呈现数据。

- GitBook 在 Markdown 的基础上使用了自定义的语法。Astro 支持通过可选的 [Markdoc 集成](/zh-cn/guides/integrations-guide/markdoc/)来支持 Markdoc，其特性与你在 GitBook 中使用的语法类似。

## 从 GitBook 切换到 Astro

要将 GitBook 文档站点转换为 Astro，可以从我们的官方 [Starlight 文档主题模版](https://starlight.astro.build)开始操作，或者在我们的 [主题展示](https://astro.build/themes?search=&categories%5B%5D=docs)中查看更多社区文档主题。

你可以通过 `create astro` 命令传递一个 `--template` 参数来启动一个带有我们官方起始器的新 Astro 项目。或者，你可以[从 GitHub 上任何现有的 Astro 仓库开始一个新项目](/zh-cn/install/auto/#入门模板)。

  <PackageManagerTabs>
    <Fragment slot="npm">
    ```shell
    npm create astro@latest -- --template starlight
    ```
    </Fragment>
    <Fragment slot="pnpm">
    ```shell
    pnpm create astro@latest --template starlight
    ```
    </Fragment>
    <Fragment slot="yarn">
    ```shell
    yarn create astro --template starlight
    ```
    </Fragment>
  </PackageManagerTabs>

一旦你有了一个新的 Astro 项目，你就可以将你现有的 GitBook 内容同步到你的新 Astro 项目中。GitBook 有一个 [Git 同步功能](https://docs.gitbook.com/product-tour/git-sync)，可以自动将你的 GitBook 内容同步到 GitHub/GitLab 仓库。

要直接同步到文档模板的内容集合，请指定 `src/content/docs/en` 或 `src/content/docs` 作为项目目录。

:::caution
启用 Git 同步时，一定要将优先级设定为 "**GitBook 至 GitHub**"。这将确保你的 GitBook 内容被同步到你的 GitHub 仓库。否则，你将覆盖你现有的 GitBook 内容。
:::

同步内容后，你现在将在你的 Astro 仓库中拥有一份你的 GitBook 内容的副本。禁用 git 同步以防止未来与 GitBook 的同步。

请注意，虽然你现在已经将你的内容迁移到了你的 Astro 项目中，但它并不能立即使用。要在你的 Astro 站点中使用这些内容，你需要花费一些时间手动将 GitBook 的语法改为与 Astro 兼容的格式。具体来说：

- Astro 的 [Markdoc 集成](/zh-cn/guides/integrations-guide/markdoc/) 要求文件扩展名为 `.mdoc`。这是为了避免与其他 Markdown 扩展名如 `.mdx` 和 `.md` 冲突。
- GitBook 语法与 Markdoc 不同，其中表示关闭标签的 `/` 前缀在 GitBook 文件中被替换为 `end`。你需要在你的文件中更新这种符号。
- GitBook 的一些特性依赖于自定义组件。这些组件在 Astro 中不存在，必须通过 [Markdoc 的配置 `tags` 属性](/zh-cn/guides/integrations-guide/markdoc/#将-astro-组件作为-markdoc-标签) 创建并添加到你的项目中，或从你的文件中删除。

## 社区资源

- 添加你自己的！
